home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Languages / MPW Oberon 2.1168 / OInterfaces / DigitalSignature.mod < prev    next >
Encoding:
Text File  |  1995-08-10  |  16.5 KB  |  381 lines  |  [TEXT/MPS ]
  1. (*
  2.      File:        DigitalSignature.mod
  3.  
  4.      Contains:    Digital Signature Interfaces.
  5.  
  6.      Version:    Technology:    AOCE toolbox 1.02
  7.                  Package:    Universal Interfaces 2.1ß1 in “MPW Prerelease” on ETO #17
  8.  
  9.      Copyright:    © 1984-1995 by Apple Computer, Inc.
  10.                  All rights reserved.
  11.  
  12.      Bugs?:        If you find a problem with this file, use the Apple Bug Reporter
  13.                  stack.  Include the file and version information (from above)
  14.                  in the problem description and send to:
  15.                      Internet:    apple.bugs.applelink.apple.com
  16.                      AppleLink:    APPLE.BUGS
  17.  
  18. *)
  19.  
  20. (*$TAGS-*)
  21. (*$CALLING PASCAL*)
  22. MODULE DigitalSignature;
  23.  
  24. IMPORT SYSTEM, Types, Memory, Files;
  25.  
  26. (* $PUSH*)
  27. (* $ALIGN MAC68K*)
  28. (* $LibExport+*)
  29.  
  30. CONST
  31.     kSIGNewContext*                = 1900;
  32.     kSIGDisposeContext*            = 1901;
  33.     kSIGSignPrepare*                = 1902;
  34.     kSIGSign*                    = 1903;
  35.     kSIGVerifyPrepare*            = 1904;
  36.     kSIGVerify*                    = 1905;
  37.     kSIGDigestPrepare*            = 1906;
  38.     kSIGDigest*                    = 1907;
  39.     kSIGProcessData*                = 1908;
  40.     kSIGShowSigner*                = 1909;
  41.     kSIGGetSignerInfo*            = 1910;
  42.     kSIGGetCertInfo*                = 1911;
  43.     kSIGGetCertNameAttributes*    = 1912;
  44.     kSIGGetCertIssuerNameAttributes* = 1913;
  45.     kSIGFileIsSigned*            = 2500;
  46.     kSIGSignFile*                = 2501;
  47.     kSIGVerifyFile*                = 2502;
  48.  
  49.     kSIGCountryCode*                = 0;
  50.     kSIGOrganization*            = 1;
  51.     kSIGStreetAddress*            = 2;
  52.     kSIGState*                    = 3;
  53.     kSIGLocality*                = 4;
  54.     kSIGCommonName*                = 5;
  55.     kSIGTitle*                    = 6;
  56.     kSIGOrganizationUnit*        = 7;
  57.     kSIGPostalCode*                = 8;
  58.  
  59.     
  60. TYPE
  61.     SIGNameAttributeType* = INTEGER;
  62.  
  63. (* 
  64. Certificate status codes returned in SIGCertInfo or SIGSignerInfo from
  65. either SIGGetCertInfo or SIGGetSignerInfo respectively. kSIGValid means that
  66. the certificate is currently valid. kSIGPending means the certificate is
  67. currently not valid - but will be.  kSIGExpired means the certificate has
  68. expired. A time is always associated with a SIGCertStatus.  In each case the
  69. time has a specific interpretation.  When the status is kSIGValid the time is
  70. when the certificate will expire. When the status is kSIGPending the time is
  71. when the certificate will become valid. When the status is kSIGExpired the time
  72. is when the certificate expired. In the SIGCertInfo structure, the startDate
  73. and endDate fields hold the appropriate date information.  In the SIGSignerInfo
  74. structure, this information is provided in the certSetStatusTime field. In the
  75. SIGSignerInfo struct, the status time is actually represented by the SIGSignatureStatus
  76. field which can contain any of the types below. NOTE*: The only time you will get 
  77. a kSIGInvalid status is when it pertains to a SIGSignatureStatus field and only when
  78. you get a signature that was created after the certificates expiration date, something
  79. we are not allowing on the Mac but that may not be restricted on other platforms. Also, 
  80. it will not be possible to get a kSIGPending value for SIGSignatureStatus on the Mac but
  81. possibly allowed by other platforms.
  82. *)
  83. (* Values for SIGCertStatus or SIGSignatureStatus *)
  84.  
  85. CONST
  86.     kSIGValid*                    = 0;                            (* possible for either a SIGCertStatus or SIGSignatureStatus *)
  87.     kSIGPending*                    = 1;                            (* possible for either a SIGCertStatus or SIGSignatureStatus *)
  88.     kSIGExpired*                    = 2;                            (* possible for either a SIGCertStatus or SIGSignatureStatus
  89.     * possible only for a SIGSignatureStatus *)
  90.     kSIGInvalid*                    = 3;
  91.  
  92.     
  93. TYPE
  94.     SIGCertStatus* = INTEGER;
  95.  
  96.     SIGSignatureStatus* = INTEGER;
  97.  
  98. (* Gestalt selector code - returns toolbox version in low-order word *)
  99.  
  100. CONST
  101.     gestaltDigitalSignatureVersion* = LONG("dsig");
  102.  
  103. (* Number of bytes needed for a digest record when using SIGDigest *)
  104.     kSIGDigestSize*                = 16;
  105.  
  106.     
  107. TYPE
  108.     SIGDigestData* = ARRAY (*ΔΔ[0..*)kSIGDigestSize(*ΔΔ -1]ΔΔ*) OF Types.Byte;
  109.     SIGDigestDataPtr* = POINTER TO SIGDigestData (*ΔΔ Types.Byte*);
  110.  
  111.     SIGCertInfo* = RECORD
  112.         startDate*:                LONGINT;                                (* cert start validity date *)
  113.         endDate*:                LONGINT;                                (* cert end validity date *)
  114.         certStatus*:                SIGCertStatus;                            (* see comment on SIGCertStatus for definition *)
  115.         certAttributeCount*:        LONGINT;                                (* number of name attributes in this cert *)
  116.         issuerAttributeCount*:    LONGINT;                                (* number of name attributes in this certs issuer *)
  117.         serialNumber*:            Types.Str255;                                    (* cert serial number *)
  118.     END;
  119.  
  120.     SIGCertInfoPtr* = POINTER TO SIGCertInfo;
  121.  
  122.     SIGSignerInfo* = RECORD
  123.         signingTime*:            LONGINT;                                (* time of signing *)
  124.         certCount*:                LONGINT;                                (* number of certificates in the cert set *)
  125.         certSetStatusTime*:        LONGINT;                                (* Worst cert status time. See comment on SIGCertStatus for definition *)
  126.         signatureStatus*:        SIGSignatureStatus;                        (* The status of the signature. See comment on SIGCertStatus for definition*)
  127.     END;
  128.  
  129.     SIGSignerInfoPtr* = POINTER TO SIGSignerInfo;
  130.  
  131.     SIGNameAttributesInfo* = RECORD
  132.         onNewLevel*:                BOOLEAN;
  133.         filler1*:                BOOLEAN;
  134.         attributeType*:            SIGNameAttributeType;
  135.         attributeScript*:        Types.ScriptCode;
  136.         attribute*:                Types.Str255;
  137.     END;
  138.  
  139.     SIGNameAttributesInfoPtr* = POINTER TO SIGNameAttributesInfo;
  140.  
  141.     SIGContextPtr* = Types.Ptr;
  142.  
  143.     SIGSignaturePtr* = Types.Ptr;
  144.  
  145. (*
  146. Certificates are always in order. That is, the signers cert is always 0, the
  147. issuer of the signers cert is always 1 etc… to the number of certificates-1.
  148. You can use this constant for readability in your code.
  149. *)
  150.  
  151. CONST
  152.     kSIGSignerCertIndex*            = 0;
  153.  
  154. (*
  155. Call back procedure supplied* by developer, return false to cancel the current
  156. process.
  157. *)
  158. TYPE
  159.     SIGStatusProcPtr* = (*ΔΔ Types.ProcPtr;*) PROCEDURE (): BOOLEAN;
  160.     SIGStatusUPP* = Types.UniversalProcPtr;
  161.  
  162. CONST
  163.     uppSIGStatusProcInfo* = $00000010; (* PROCEDURE : 1 byte result; *)
  164.  
  165. PROCEDURE NewSIGStatusProc*(userRoutine: SIGStatusProcPtr): SIGStatusUPP;
  166.     (*$IF NOT GENERATINGCFM *)
  167.     INLINE PASCAL $2E9F;
  168.     (*$END*)
  169.  
  170. PROCEDURE CallSIGStatusProc*(userRoutine: SIGStatusUPP): BOOLEAN;
  171.     (*$IF NOT GENERATINGCFM*)
  172.     INLINE PASCAL $205F, $4E90;
  173.     (*$END*)
  174. (*
  175. Resource id's of standard signature icon suite, all sizes and colors are available.
  176. *)
  177.  
  178. CONST
  179.     kSIGSignatureIconResID*        = -16800;
  180.     kSIGValidSignatureIconResID*    = -16799;
  181.     kSIGInvalidSignatureIconResID* = -16798;
  182.  
  183. (* ——————————————————————————————— CONTEXT CALLS ——————————————————————————————— 
  184. To use the Digital Signature toolbox you will need a SIGContextPtr.  To create
  185. a SIGContextPtr you simply call SIGNewContext and it will create and initialize
  186. a context for you.  To free the memory occupied by the context and invalidate
  187. its internal data, call SIGDisposeContext. An initialized context has no notion
  188. of the type of operation it will be performing however, once you call
  189. SIGSignPrepare SIGVerifyPrepare, or SIGDigestPrepare, the contexts operation
  190. type is set and to switch  to another type of operation will require creating a
  191. new context. Be sure to pass the same context to corresponding toolbox calls
  192. (ie SIGSignPrepare, SIGProcessData, SIGSign)  in other words mixing lets say
  193. signing and verify calls with the same context is not allowed.
  194. *)
  195.  
  196. PROCEDURE SIGNewContext*(VAR context: SIGContextPtr): Types.OSErr;
  197.     (*$IF NOT GENERATINGCFM*)
  198.     INLINE PASCAL $203C, 2, 1900, $AA5D;
  199.     (*$END*)
  200. PROCEDURE SIGDisposeContext*(context: SIGContextPtr): Types.OSErr;
  201.     (*$IF NOT GENERATINGCFM*)
  202.     INLINE PASCAL $203C, 2, 1901, $AA5D;
  203.     (*$END*)
  204. (* ——————————————————————————————— SIGNING CALLS ——————————————————————————————— 
  205. Once you have created a SIGContextPtr, you create a signature by calling
  206. SIGSignPrepare once, followed by n calls to SIGProcessData, followed by one call
  207. toRcpt SIGSign. To create another signature on different data but for the same
  208. signer, don't dispose of the context and call SIGProcessData for the new data
  209. followed by a call SIGSign again. In this case the signer will not be prompted
  210. for their signer and password again as it was already provided.  Once you call
  211. SIGDisposeContext, all signer information will be cleared out of the context and
  212. the signer will be re-prompted.  The signer file Files.FSSpecPtr should be set to nil
  213. if you want the toolbox to use the last signer by default or prompt for a signer
  214. if none exists.  The prompt parameter can be used to pass a string to be displayed
  215. in the dialog that prompts the user for their password.  If the substring "POINTER TO 1"
  216. (without the quotes) is in the prompt string, then the toolbox will replace it
  217. with the name of the signer from the signer selected by the user.  If an empty
  218. string is passed, the following default string will be sent to the toolbox
  219. "\pSigning as POINTER TO 1.".  You can call any of the utility routines after SIGSignPrepare
  220. or SIGSign to get information about the signer or certs.
  221. *)
  222. PROCEDURE SIGSignPrepare*(context: SIGContextPtr; (*CONST*)VAR signerFile: Files.FSSpec; prompt: Types.ConstStr255Param; VAR signatureSize: Memory.Size): Types.OSErr;
  223.     (*$IF NOT GENERATINGCFM*)
  224.     INLINE PASCAL $203C, 8, 1902, $AA5D;
  225.     (*$END*)
  226. PROCEDURE SIGSign*(context: SIGContextPtr; signature: SIGSignaturePtr; statusProc: SIGStatusUPP): Types.OSErr;
  227.     (*$IF NOT GENERATINGCFM*)
  228.     INLINE PASCAL $203C, 6, 1903, $AA5D;
  229.     (*$END*)
  230. (* ——————————————————————————————— VERIFYING CALLS ——————————————————————————————— 
  231. Once you have created a SIGContextPtr, you verify a signature by calling
  232. SIGVerifyPrepare  once, followed by n calls to SIGProcessData, followed by one
  233. call to SIGVerify. Check the return code from SIGVerify to see if the signature
  234. verified or not (noErr is returned on  success otherwise the appropriate error
  235. code).  Upon successfull verification, you can call any of the utility routines
  236. toRcpt find out who signed the data.
  237. *)
  238. PROCEDURE SIGVerifyPrepare*(context: SIGContextPtr; signature: SIGSignaturePtr; signatureSize: Memory.Size; statusProc: SIGStatusUPP): Types.OSErr;
  239.     (*$IF NOT GENERATINGCFM*)
  240.     INLINE PASCAL $203C, 8, 1904, $AA5D;
  241.     (*$END*)
  242. PROCEDURE SIGVerify*(context: SIGContextPtr): Types.OSErr;
  243.     (*$IF NOT GENERATINGCFM*)
  244.     INLINE PASCAL $203C, 2, 1905, $AA5D;
  245.     (*$END*)
  246. (* —————————————————————————————— DIGESTING CALLS —————————————————————————————— 
  247. Once you have created a SIGContextPtr, you create a digest by calling
  248. SIGDigestPrepare once, followed by n calls to SIGProcessData, followed by one
  249. call to SIGDigest.  You can dispose of the context after SIGDigest as the
  250. SIGDigestData does not reference back into it.  SIGDigest returns the digest in
  251. digest.
  252. *)
  253. PROCEDURE SIGDigestPrepare*(context: SIGContextPtr): Types.OSErr;
  254.     (*$IF NOT GENERATINGCFM*)
  255.     INLINE PASCAL $203C, 2, 1906, $AA5D;
  256.     (*$END*)
  257. PROCEDURE SIGDigest*(context: SIGContextPtr; VAR digest: SIGDigestData): Types.OSErr;
  258.     (*$IF NOT GENERATINGCFM*)
  259.     INLINE PASCAL $203C, 4, 1907, $AA5D;
  260.     (*$END*)
  261. (* —————————————————————————————— PROCESSING DATA —————————————————————————————— 
  262. To process data during a digest, sign, or verify operation call SIGProcessData
  263. as many times as necessary and with any sized blocks of data.  The data needs to
  264. be processed in the same order during corresponding sign and verify operations
  265. but does not need to be processed in the same sized chunks (i.e., the toolbox
  266. just sees it as a continuous bit stream).
  267. *)
  268. PROCEDURE SIGProcessData*(context: SIGContextPtr; data: (*ΔΔUNIVΔΔ*) Types.Ptr; dataSize: Memory.Size): Types.OSErr;
  269.     (*$IF NOT GENERATINGCFM*)
  270.     INLINE PASCAL $203C, 6, 1908, $AA5D;
  271.     (*$END*)
  272. (* ——————————————————————————————— UTILITY CALLS ——————————————————————————————— 
  273. Given a context that has successfully performed a verification SIGShowSigner
  274. will  display a modal dialog with the entire distinguished name of the person
  275. who signed the data. the prompt (if supplied) will appear at the top of the
  276. dialog.  If no prompt is specified, the default prompt "\pVerification
  277. Successfull." will appear.
  278.  
  279. Given a context that has been populated by calling SIGSignPrepare, SIGSign or a
  280. successful SIGVerify, you can make the remaining utility calls*:
  281.  
  282. SIGGetSignerInfo will return the SignerInfo record.  The certCount can be used
  283. toRcpt index into the certificate set when calling SIGGetCertInfo,
  284. SIGGetCertNameAttributes or SIGGetCertIssuerNameAttributes. The signingTime is
  285. only defined if the call is made after SIGSign  or SIGVerify. The certSetStatus
  286. will tell you the best status of the entire certificate set while
  287. certSetStatusTime will correspond to the time associated with that status (see
  288. definitions above).
  289.  
  290. SIGGetCertInfo will return the SIGCertInfo record when given a valid index into
  291. the cert set in  certIndex.  Note*: The cert at index kSIGSignerCertIndex is
  292. always the signers certificate.  The  serial number, start date and end date
  293. are there should you wish to display that info.  The  certAttributeCount and
  294. issuerAttributeCount provide the number of parts in the name of that certificate
  295. or that certificates issuer respectively.  You use these numbers to index into
  296. either SIGGetCertNameAttributes or SIGGetCertIssuerNameAttributes to retrieve
  297. the name. The certStatus will tell you the status of the certificate while
  298. certStatusTime will correspond to the time associated with that status (see
  299. definitions above).
  300.  
  301. SIGGetCertNameAttributes and SIGGetCertIssuerNameAttributes return name parts
  302. of the certificate at  certIndex and attributeIndex.  The newLevel return value
  303. tells you wether the name attribute returned is at the same level in the name
  304. hierarchy as the previous attribute.  The type return value tells you  the type
  305. of attribute returned. nameAttribute is the actual string containing the name
  306. attribute.   So, if you wanted to display the entire distinguished name of the
  307. person who's signature was just validated you could do something like this;
  308.  
  309.     (…… variable declarations and verification code would preceed this sample ……)
  310.  
  311.     error* = SIGGetCertInfo(verifyContext, kSIGSignerCertIndex, &certInfo);
  312.     HandleErr(error);
  313.  
  314.     for (i* = 0; i <= certInfo.certAttributeCount-1; i++)
  315.         (
  316.         error* = SIGGetCertNameAttributes(
  317.             verifyContext, kSIGSignerCertIndex, i, &newLevel, &type, theAttribute);
  318.         HandleErr(error);
  319.         DisplayNamePart(theAttribute, type, newLevel);
  320.         )
  321. *)
  322. PROCEDURE SIGShowSigner*(context: SIGContextPtr; prompt: Types.ConstStr255Param): Types.OSErr;
  323.     (*$IF NOT GENERATINGCFM*)
  324.     INLINE PASCAL $203C, 4, 1909, $AA5D;
  325.     (*$END*)
  326. PROCEDURE SIGGetSignerInfo*(context: SIGContextPtr; VAR signerInfo: SIGSignerInfo): Types.OSErr;
  327.     (*$IF NOT GENERATINGCFM*)
  328.     INLINE PASCAL $203C, 4, 1910, $AA5D;
  329.     (*$END*)
  330. PROCEDURE SIGGetCertInfo*(context: SIGContextPtr; certIndex: LONGINT; VAR certInfo: SIGCertInfo): Types.OSErr;
  331.     (*$IF NOT GENERATINGCFM*)
  332.     INLINE PASCAL $203C, 6, 1911, $AA5D;
  333.     (*$END*)
  334. PROCEDURE SIGGetCertNameAttributes*(context: SIGContextPtr; certIndex: LONGINT; attributeIndex: LONGINT; VAR attributeInfo: SIGNameAttributesInfo): Types.OSErr;
  335.     (*$IF NOT GENERATINGCFM*)
  336.     INLINE PASCAL $203C, 8, 1912, $AA5D;
  337.     (*$END*)
  338. PROCEDURE SIGGetCertIssuerNameAttributes*(context: SIGContextPtr; certIndex: LONGINT; attributeIndex: LONGINT; VAR attributeInfo: SIGNameAttributesInfo): Types.OSErr;
  339.     (*$IF NOT GENERATINGCFM*)
  340.     INLINE PASCAL $203C, 8, 1913, $AA5D;
  341.     (*$END*)
  342. (* ——————————————————————————— FILE SIGN & VERIFY CALLS —————————————————————————— 
  343. These calls allow you to detect the presence of a standard signtaure in a file as 
  344. well as sign and verify files in a standard way.  An example of this is the Finder, 
  345. which uses these calls to allow the user to "drop sign" a file.
  346.  
  347. To detect if a file is signed in the standard way, pass the Files.FSSpec of the file to SIGFileIsSigned.
  348. A result of noErr means the file is in fact signed, otherwise, a kSIGNoSignature error will
  349. be returned.
  350.  
  351. Once you have created a SIGContextPtr, you can make calls to either sign or verify a file in
  352. a standard way*: 
  353.  
  354. To sign a file, call SIGSignPrepare followed by 'n' number of calls to SIGSignFile,
  355. passing it the file spec for each file you wish to sign in turn.  You supply the context, the signature 
  356. size that was returned from SIGSignPrepare and an optional call back proc.  The call will take care of all
  357. the processing of data and affixing the signature to the file. If a signature already exists in the file, 
  358. it is replaced with the newly created signature.
  359.  
  360. To verify a file that was signed using SIGSignFile, call SIGVerifyFile passing it a new context and 
  361. the file spec.  Once this call has completed, if the verification is successfull, you can pass the context 
  362. to SIGShowSigner to display the name of the person who signed the file.
  363. *)
  364. PROCEDURE SIGFileIsSigned*((*CONST*)VAR fileSpec: Files.FSSpec): Types.OSErr;
  365.     (*$IF NOT GENERATINGCFM*)
  366.     INLINE PASCAL $203C, 2, 2500, $AA5D;
  367.     (*$END*)
  368. PROCEDURE SIGSignFile*(context: SIGContextPtr; signatureSize: Memory.Size; (*CONST*)VAR fileSpec: Files.FSSpec; statusProc: SIGStatusUPP): Types.OSErr;
  369.     (*$IF NOT GENERATINGCFM*)
  370.     INLINE PASCAL $203C, 8, 2501, $AA5D;
  371.     (*$END*)
  372. PROCEDURE SIGVerifyFile*(context: SIGContextPtr; (*CONST*)VAR fileSpec: Files.FSSpec; statusProc: SIGStatusUPP): Types.OSErr;
  373.     (*$IF NOT GENERATINGCFM*)
  374.     INLINE PASCAL $203C, 6, 2502, $AA5D;
  375.     (*$END*)
  376.  
  377. (* $ALIGN RESET*)
  378. (* $POP*)
  379.  
  380.  END DigitalSignature.
  381.